MCP PipeRun

Integração completa com a API do PipeRun CRM.

Usa n8n? Clique aqui para o Guia Completo de Integração com n8n

Inclui: instalação passo a passo, exemplos práticos, workflows prontos e referência completa de endpoints.

Duas Versões Disponíveis

Qual escolher?

• Usa Claude, Cursor ou outro cliente MCP? → Use o MCP Server
• Usa n8n, Zapier, Make ou precisa de API REST? → Use o HTTP Server

MCP Server (para Claude/Cursor)

Servidor MCP (Model Context Protocol) que permite assistentes de IA interagirem diretamente com o PipeRun.

Recursos

• 32 ferramentas para gerenciar completamente o PipeRun
• CRUD completo para deals, persons, companies, activities e notes
• Busca por oportunidades e pessoas
• Respostas formatadas - resumos legíveis ao invés de JSON bruto
• Retry automático com backoff exponencial para resiliência
• Autenticação flexível - via variável de ambiente ou por chamada
• TypeScript com tipagem completa
• Testes automatizados com Vitest
• CI/CD com GitHub Actions

Pré-requisitos

• Node.js v18 ou superior
• npm (geralmente instalado junto com o Node.js)
• Token da API do PipeRun

Instalação

1. Clone o repositório:

git clone https://github.com/dinhogehm/mcp-piperun.git
cd mcp-piperun

2. Instale as dependências e compile:

cd piperun-mcp-server
npm install
npm run build

Como Obter o Token da API

1. Faça login na sua conta do PipeRun
2. Acesse Configurações > Integrações > API
3. Copie o seu Token de API

Configuração

Opção 1: Variável de Ambiente (Recomendado)

Configure PIPERUN_API_TOKEN no seu ambiente:

{
  "mcpServers": {
    "piperun": {
      "command": "node",
      "args": ["/caminho/para/mcp-piperun/piperun-mcp-server/build/index.js"],
      "env": {
        "PIPERUN_API_TOKEN": "seu_token_aqui"
      }
    }
  }
}

Opção 2: Token por Chamada

Passe o api_token como argumento em cada chamada de ferramenta.

Locais do Arquivo de Configuração

• Claude Desktop (MacOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%/Claude/claude_desktop_config.json
• Claude Desktop (Linux): ~/.config/Claude/claude_desktop_config.json
• Claude Code: .claude/settings.json

Ferramentas Disponíveis (32 total)

Oportunidades (Deals) - 7 ferramentas

Pessoas (Persons) - 6 ferramentas

Empresas (Companies) - 5 ferramentas

Atividades - 6 ferramentas

Notas - 3 ferramentas

Outros - 5 ferramentas

Exemplos de Uso

> Liste minhas oportunidades abertas

[12345] Projeto ABC | R$ 50.000 | Aberta | Etapa: Negociação | Responsável: João
[12346] Contrato XYZ | R$ 25.000 | Aberta | Etapa: Proposta | Responsável: Maria

📊 Total: 2 | Página: 1/1

> Crie uma oportunidade "Novo Cliente" no funil 1, etapa 1, responsável 100

✅ Oportunidade criada com sucesso!
[12347] Novo Cliente | Sem valor | Aberta | Etapa: Prospecção | Responsável: João

> Busque pessoas com nome "Silva"

🔍 Busca por "Silva":

[100] João Silva | joao@email.com | 11999999999 | Empresa: ABC Ltda
[101] Maria Silva | maria@email.com | Sem contato | Empresa: N/A

📊 Total: 2 | Página: 1/1

Desenvolvimento

# Instalar dependências
npm install

# Compilar
npm run build

# Modo watch (recompila automaticamente)
npm run watch

# Executar linter
npm run lint

# Formatar código
npm run format

# Executar testes
npx vitest run

# Depuração com MCP Inspector
npm run inspector

Estrutura do Projeto

mcp-piperun/
├── .github/
│   └── workflows/
│       └── ci.yml              # GitHub Actions CI/CD
├── piperun-mcp-server/
│   ├── src/
│   │   ├── index.ts           # Código principal
│   │   └── __tests__/         # Testes
│   ├── build/                  # Código compilado
│   ├── eslint.config.js       # Configuração ESLint
│   ├── vitest.config.ts       # Configuração Vitest
│   ├── .prettierrc            # Configuração Prettier
│   ├── package.json
│   └── tsconfig.json
├── .gitignore
└── README.md

Changelog

v0.3.0

• Adicionadas ferramentas de delete (deal, person, company, activity, note)
• Adicionadas ferramentas de atividades (get, create, update)
• Adicionadas ferramentas de busca (search_deals, search_persons)
• Adicionado retry com backoff exponencial (3 tentativas)
• Adicionada autenticação via variável de ambiente PIPERUN_API_TOKEN
• Respostas formatadas com resumos legíveis
• Configuração de ESLint + Prettier
• Testes automatizados com Vitest
• CI/CD com GitHub Actions

v0.2.0

• Adicionadas ferramentas: list_persons, get_person, update_person, get_deal, create_deal, update_deal
• Timeout de 30 segundos nas requisições
• Validação de argumentos para todas as operações

v0.1.0

• Versão inicial com ferramentas básicas

HTTP Server (para n8n/Zapier/Make)

Servidor HTTP/REST para integração via requisições HTTP tradicionais.

Instalação Rápida

cd piperun-http-server
npm install
npm run build

Executando

# Com variável de ambiente
PIPERUN_API_TOKEN=seu_token npm start

# Servidor roda em http://localhost:3000

Uso com n8n

1. Inicie o servidor HTTP
2. No n8n, use o node HTTP Request
3. Configure:
   • URL: http://localhost:3000/deals
   • Header: X-PipeRun-Token: seu_token

Endpoints Principais

Docker

docker build -t piperun-http-server ./piperun-http-server
docker run -p 3000:3000 -e PIPERUN_API_TOKEN=seu_token piperun-http-server

📖 Documentação completa: piperun-http-server/README.md

Referências

• Documentação da API do PipeRun
• Model Context Protocol (MCP)
• MCP SDK para TypeScript

Licença

Este projeto é disponibilizado como código aberto.